docs: add maintainer reference for the CI/CD workflows#90
Merged
Conversation
Add a maintainer-facing reference under maintainers/workflows/ documenting every GitHub Actions workflow. A main index (README) presents the cross-cutting conventions (SHA-pinned actions, least-privilege permissions, per-job timeouts, concurrency, weekly scheduled scans, fork-safety, and required checks as the real gate) and links, grouped by theme, to one page per workflow. Each per-workflow page follows a common template: what it is for (pedagogical), when it runs, how it runs, permissions and security, and a "handle with care" section capturing the non-obvious decisions that must not be changed without understanding why. The release and analyzers pages link to the existing ReleaseDryRun guide and ADR 0001 rather than duplicating them. All pages are provided in English (canonical) and French, per CONTRIBUTING.md and the repository language policy.
Wire the new workflow pages into the maintainer documentation so no page is orphaned: - Add a maintainers/ landing index (README.md + README.fr.md) that GitHub auto-renders, listing the workflow reference, the release dry-run runbook, and the ADR log. - Rename the workflow index from README.en.md to README.md so it auto-renders when browsing maintainers/workflows/, and update the inbound links. - Add breadcrumbs from the workflow reference up to the maintainers index, and reciprocal links from the ReleaseDryRun runbook to the release and release-dryrun reference pages (plus a language switcher on the runbook). No content in the ADR is changed; it stays a standalone decision record, now linked from the index and the analyzers page.
The adoption note pointed ADRs at doc/adr/, but the repository keeps them under maintainers/adr/ (where ADR 0001 lives). Align the guide with the actual location.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add a maintainer-facing reference under
maintainers/workflows/that documents every GitHub Actions workflow — an index page plus one page per workflow, in English (canonical) and French. It captures the why and the "handle with care" traps that the YAML comments hold line-by-line, so a maintainer knows what not to change before touching a workflow.Type of change
Changes
maintainers/workflows/README.en.md/README.fr.md— the index: cross-cutting conventions (SHA-pinned actions, least-privilege permissions, per-job timeouts, concurrency, weekly scheduled scans, fork-safety, required checks as the real gate) and a themed table of contents.ci,sonar,analyzers,commit-lint(build & quality)codeql,dependency-review,scorecard(security & supply chain)release,release-dryrun(release)dependabot-automerge(dependency maintenance)release/release-dryrunpages link to the existingmaintainers/ReleaseDryRun.*.mdguide, and theanalyzerspage links tomaintainers/adr/0001-lock-the-analyzer-roslyn-floor.md, rather than duplicating them.Testing
dotnet build FirstClassErrors.slndotnet test FirstClassErrors.slnFirstClassErrors.Analyzers.UnitTests)Not applicable — documentation only, no code touched. All relative links in the new pages were validated to resolve.
Documentation
doc/updatedRelated issues
Generated by Claude Code